Monster Media 1996 #15

home *** CD-ROM | disk | FTP | other *** search

/ Monster Media 1996 #15 / Monster Media Number 15 (Monster Media)(July 1996).ISO / netmail / rnr214.zip / EXEC23P.ZIP / EXEC.DOC < prev next >

Wrap

Text File | 1990-10-11 | 14KB | 329 lines

An EXEC function with memory swap ================================= Public domain software by Thomas Wagner Ferrari electronic GmbH Beusselstrasse 27 D-1000 Berlin 21 Germany BIXname: twagner Version 2.3, released 90-10-11. The usual disclaimers on warranties and fitness for any purpose apply. This is public domain software, so there are no restrictions at all on use (private or commercial), or on distribution by any media. No royalty or license payments are necessary to use this software. Limited support is available via BIX, BIXmail your bug reports or questions to 'twagner'. This archive contains the sources for an 'EXEC' function for Turbo C (versions 1.x, 2.x, and C++ 1.x), Microsoft C (versions 5.1 and 6.0), Watcom C (version 8.0), and Turbo Pascal (versions 4.x/5.x) that optionally swaps out the memory image of the calling program to a temporary file or to EMS, and shrinks down to a minimal core before executing the program. This allows chaining or spawning to memory-hungry programs, and it eases building of DOS menu-systems. The memory used when swapping is less than 1k, plus the memory needed for a copy of the environment. If you pass a new environment to the spawned program, space for two copies of the environment are needed. EMS (LIM 3.0 or above) is used automatically if there is enough space left, otherwise a temporary file is created. If the "TEMP=" or "TMP=" environment variable is present, the temporary file is created in the directory specified by this variable, otherwise it is created in the current directory. INTERFACE ========= Pascal: function do_exec (xfn: filename; pars: string128; spwn: integer; needed: word; newenv: boolean): integer; C: extern int do_exec (char *xfn, char *pars, int spwn, unsigned needed, char **envp); Parameters: xfn is a string containing the name of the file to be executed. If the string is empty, the COMSPEC environment variable is used to load a copy of COMMAND.COM or its equivalent. If the filename does not include a path, the current PATH is searched after the default. If the filename does not include an extension, the path is scanned for a COM or EXE file in that order. pars The program parameters. spwn If 1, the function will return, if necessary after swapping the memory image. If -1, EMS will not be used when swapping. If 0, the function will terminate after the EXECed program returns. NOTE: If the program file is not found, the function will always return with the appropriate error code, even if 'spwn' is 0. needed The memory needed for the program in paragraphs. If not enough memory is free, the program will be swapped out. Use 0 to never swap, $ffff to always swap. If 'spwn' is false, this parameter is irrelevant. Pascal only: newenv If this parameter is FALSE, the environment of the spawned program is a copy of the parent's environment. If it is TRUE, a new environment is created which includes the modifications from previous 'putenv' calls. C only: envp The environment to be passed to the spawned program. If this parameter is NULL, a copy of the parent's environment is used (i.e. 'putenv' calls have no effect). If non-NULL, envp must point to an array of pointers to strings, terminated by a NULL pointer (the standard variable 'environ' may be used). Return value: 0000..00FF: The EXECed Program's return code (0..255 decimal) 0100: Error writing swap file (256 decimal) 0200: Program file not found (512 decimal) 03xx: DOS-error-code xx calling EXEC (768..1023 decimal) 0400: Error allocating environment buffer (1024 decimal) 0500: No room in low program memory, move spawn module to end of link (1280 decimal) RESTRICTIONS ============ The assembler module "spawn" must not be the first module linked. Either put it into a library, or specify spawn.obj as one of the last objects in the link command or the Turbo project file. The spawn module will overwrite about 1k at the start of the program image. Although the contents of this area will be saved, they may not contain parts of the spawn module itself, since this would destroy the code being executed. The calling program may not have interrupt handlers installed when calling the do_exec function. This includes handlers for Control C and critical errors. All open files will stay open during the EXEC call. This reduces the number of handles available to the child process. The "C_FILE_INFO" environment variable created by the standard C spawn is not supported. BAT-files and internal commands are not automatically processed. You can execute those by calling the do_exec function twice, for example: (C) retcode = do_exec ("dir", "*.*", 1, 0xffff, environ); if (retcode == 0x200) retcode = do_exec ("", "/c dir *.*", 1, 0xffff, environ); (P) retcode := do_exec ('dir', '*.*', 1, $ffff, true); if (retcode = $200) retcode := do_exec ('', '/c dir *.*', 1, $ffff, true); CAUTIONS ======== The functions should be compatible with DOS versions down to DOS 2.21, but they have been tested under DOS 3.3 and DOS 4.0 only. Spawning a command that exits and stays resident (TSR), like PRINT or Sidekick, will fragment memory and prevent a return to the calling program. This should, however, not crash the system. Allocated EMS pages are released, but a swap file is not deleted. The memory image of the calling program should be contiguous. This is always guaranteed if you use the standard Turbo C/Pascal allocation routines only. The swapper is able to swap non-contiguous blocks such as those created by the Microsoft far allocation routines. However, to do this, the swapper has to use undocumented fields in the memory control blocks, and modify DOS memory control blocks directly. This may lead to incompatibilities in later versions of DOS, or in DOS substitutes or emulators. When debugging the assembler module, take care not to set breakpoints in the code while it is being swapped out. Those breakpoints (INT 3 instructions) will be swapped back in later without the debugger knowing about it, and cause quite strange results when you run through the code for the second time. Note that Turbo Pascal kills all debugging info when loading external assembler modules, so you can't step through SPAWN with TD in source mode. You will have to open the CPU window to step through SPAWN if required. Turbo C does not have this problem. CONTENTS ======== This archive contains the following files: SPAWN.ASM The main swap/exec function This file is common to the C and Pascal versions. It must be assembled with Turbo-Assembler for use with Pascal. The C version can be assembled with TASM (specify /JMASM51 on the command line) or MASM 5.1. To assemble: tasm /DPASCAL spawn; For Turbo Pascal, near calls tasm /DPASCAL /DFARCALL spawn; For Turbo Pascal, far calls ?asm spawn; For C (default small model) ?asm /DMODL=xxx spawn; For C (model 'xxx') Example: masm /DMODL=large spawn; Large model C tasm /DMODL=medium /JMASM51 spawn; Medium model C SPAWNPN.OBJ SPAWN assembled for use with Pascal, near calls SPAWNCS.OBJ SPAWN assembled for use with C (small model) Rename the appropriate file to 'SPAWN.OBJ' for use with your compiler. The CS file has been assembled with the /MX switch for case-sensitive external linking. Note for Turbo Pascal: You can use the near call version of SPAWN even when compiling with "force far calls" by enclosing the external definition of do_spawn with {$F-} and {$F+}. EXEC.PAS Interface routines for Turbo Pascal (5.x) EXEC.C Interface routines for Turbo C / MS-C COMPAT.H MS-C/TC Compatibility definitions for C These files prepare the parameters for the main spawn function, and handle the file search and environment processing. EXTEST.C Turbo C Test program for EXEC EXTEST.PRJ Turbo C 2.0 Project file for test program EXTEST.PAS Turbo Pascal Test program for EXEC The EXTEST program tests the functionality of the do_exec function. It expects you to input a DOS-command and its parameters, separated by a comma. Entering an empty line will spawn a copy of COMMAND.COM without parameters. The Turbo Pascal version of EXEC.PAS includes replacement functions for the environment access functions 'envcount', 'envstr', and 'getenv', plus an additional function, 'putenv'. This function allows you to add strings to the environment for the spawned process. The definition is procedure putenv (envvar: string); with 'envstr' containing a string of the form 'ENVVAR=value'. The '=' is required. To delete an environment string, use 'ENVVAR='. Please use the environment functions from the EXEC unit only, do not mix them with calls to the DOS unit functions. Revision History ================ Changes from version 1.0 to 2.0: 1) Problem fixes - Problems with EMS drivers that return handles above 255 have been fixed. - Bug that prevented deletion of temporary file has been fixed. - The Division by Zero interrupt vector is patched to an IRET and restored when swapping back in. - The /DFARCALL define has been added to the assembler module to allow assembling for Turbo Pascal with "Force Far Calls" set. 2) Enhancements - The TMP/TEMP environment string is checked for validity, and is ignored if it points to a non-existent directory. - For DOS versions 3.0 and above, the temporary file is created using the special DOS function. This eliminates the extra overhead for generating a unique filename. - The C version is now compatible with Microsoft C 5.x. - Non-contiguous memory blocks can be swapped. - The 'spwn' parameter to the do_exec function has been changed to allow EMS usage to be controlled. It can now have the values -1, 0, and 1. For Pascal, the type of the parameter has been changed from boolean to integer. The internal assembler routine takes an additional method parameter, it no longer uses the first byte of the swap-filename to determine swapping method. Changes from version 2.0 to 2.1/2.2: Several bugs in spawn.asm were fixed, no other changes. Changes from version 2.1/2.2 to 2.3: - When swapping to a file, the swap file is now closed before spawning. This frees another file handle, and avoids problems with programs (for example chkdsk) falsely claiming lost clusters. - If the program consisted of multiple memory blocks (MS-C large model, or blocks allocated with farmalloc), only the first (main program/data) block was swapped out completely. All other blocks in the MCB chain were swapped short if their length was not a multiple of 16k bytes. This could cause problems on return. - If the spawn module was linked as one of the first modules in a program, the code in the module itself could get clobbered by moving the code and setting up the data at the start of the program image. The spawn module now checks that it is located high enough in memory. - An unnecessary "offset" operator was removed from several statements in the assembler module to avoid spurious warnings when assembling with MASM /W2. You will still get warnings when assembling with /W2, but those warnings can not be eliminated (or at least I don't know how). A symbol name was fixed to allow assembling with /ml. - A pragma for Watcom C 8.0 was added to compat.h (supplied by T. Frost). ACKNOWLEDGEMENTS ================ Thanks to H. Qualls, H. Gubler, J. Clinton, M. Adler, T. Frost, and other BIXen, for pointing out bugs and suggesting enhancements.